<p>A good use case of promoted attributes is to easily define the various
  parameters a script might need, for example an input and output note if
  it's processing data, or a checkbox to define a particular change in behavior
  for the script.</p>
<p>
  <img src="Using promoted attributes .png">
</p>
<h2>Using check boxes to toggle flags</h2>
<p>Instead of asking the user to modify a boolean value in the script, it's
  much more intuitive to use a checkbox for it as a promoted attribute.</p>
<p>To do so, first define the promoted attribute:</p><pre><code class="language-text-x-trilium-auto">#label:groupByExtension="promoted,alias=Group by extension,single,boolean"</code></pre>
<p>Then use it:</p><pre><code class="language-application-javascript-env-backend">const byExtension = api.currentNote.getLabelValue("groupByExtension") === "true";
if (byExtension) {
	// Do something.
}</code></pre>
<p>This will work equally well in both front-end and back-end scripts.</p>
<h2>Using relations to select notes</h2>
<p>One common use case for a script is to read data from another note and
  perhaps output its result in another note. To do so we need to define the
  following promoted attributes:</p><pre><code class="language-text-x-trilium-auto">#relation:input="promoted,alias=Input,single" #relation:output="promoted,alias=Output,single"</code></pre>
<p>Once we have this, we can add some basic error handling to ensure that
  the fields are completed by the user:</p><pre><code class="language-application-javascript-env-backend">const inputNoteId = api.currentNote.getRelationValue("input");
if (!inputNoteId) {
	api.showError("Missing input.");
    return;
}

const outputNoteId = api.currentNote.getRelationValue("output");
if (!outputNoteId) {
    api.showError("Missing output.");
    return;
}</code></pre>
<p>Note that here we are using <code>api.showError</code> which is only available
  for frontend notes. If you are writing a backend note, simply remove <code>api.showError</code> but
  the user will no feedback on why the script did not execute properly.</p>
<p>Afterwards we can simply read the note and do something with it:</p><pre><code class="language-application-javascript-env-backend">const note = api.getNote(inputNoteId);
if (!note) {
	return;
}
const content = note.getContent().toString("utf-8");</code></pre>